Function: insertWithin(domInsertionElement, domElementOrMarkupStringOrCSSSelector, functionCallback(domElement))

Description: Inserts a target DOM element within an element, markup string, or CSS selector referenced element in the DOM.

Returns: domElement, or $A object if chained.

Note: Before the new content is inserted into the target DOM element, all preexisting content will be cleaned and removed to prevent memory leaks. The insertWithin() function is the literal opposite of insert().

Example:

// Insert a DOM element within another element targetted with a CSS selector
var myElement = $A.insertWithin("#myTargetNodeId", domElement);

// Insert a markup string element within another DOM element
var myElement = $A.insertWithin(domElement, '<div>Here we are now, entertain us.</div>');

// Insert one element referenced by a CSS selector within another DOM element
var myElement = $A.insertWithin(domElement, "#myTargetNodeToMove");

// Insert a DOM element within another DOM element and exicute a callback when done
var myElement = $A.insertWithin(domElementToTarget, domElementToMove, function(domElementToMove) {
  // Do something with domElementToMove after the insertion is complete.
});

// Or the same using chaining

// Insert a DOM element within another element targetted with a CSS selector
var myChain = $A(domElement).insertWithin("#myTargetNodeId");

// Insert a markup string element within another DOM element
var myChain = $A('<div>Here we are now, entertain us.</div>').insertWithin(domElement);

// Insert one element referenced by a CSS selector within another DOM element
var myChain = $A("#myTargetNodeToMove").insertWithin(domElement);

// Insert a DOM element within another DOM element and exicute a callback when done
var myChain = $A(domElementToMove).insertWithin(domElementToTarget, function(domElementToMove) {
  // Do something with domElementToMove after the insertion is complete.
});

// To return the modified element within a chain, use the "return()" method.

var myElement = myChain.return();